home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / catD / vmeio.z / vmeio
Encoding:
Text File  |  2002-10-03  |  14.6 KB  |  397 lines
  1.  
  2.  
  3.  
  4. vvvvmmmmeeeeiiiioooo((((DDDD3333))))                                                            vvvvmmmmeeeeiiiioooo((((DDDD3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      vmeio_piomap_alloc, vmeio_piomap_addr, vmeio_piomap_done,
  10.      vmeio_piomap_free, vmeio_pio_bcopyin, vmeio_pio_bcopyout,
  11.      vmeio_dmamap_alloc, vmeio_dmamap_addr, vmeio_dmamap_list,
  12.      vmeio_dmamap_done, vmeio_dmamap_free, vmeio_intr_alloc,
  13.      vmeio_intr_vector_get, vmeio_intr_connect, vmeio_intr_disconnect,
  14.      vmeio_intr_free, - VMEbus device driver API
  15.  
  16. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  17.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////vvvvmmmmeeee////vvvvmmmmeeeeiiiioooo....hhhh>>>>
  18.  
  19.    PPPPrrrrooooggggrrrraaaammmmmmmmeeeedddd IIIIOOOO
  20.      vmeio_piomap_t vmeio_piomap_alloc(vertex_hdl_t vme_conn,
  21.                                        device_desc_t dev_desc,
  22.                                        vmeio_space_t space,
  23.                                        iopaddr_t vmeaddr,
  24.                                        size_t byte_count,
  25.                                        size_t byte_count_max,
  26.                                        unsigned flags);
  27.  
  28.      caddr_t vmeio_piomap_addr(vmeio_piomap_t piomap,
  29.                                iopaddr_t vmeaddr,
  30.                                size_t byte_count);
  31.  
  32.      void vmeio_piomap_done(vmeio_piomap_t piomap);
  33.  
  34.      void vmeio_piomap_free(vmeio_piomap_t piomap);
  35.  
  36.      size_t vmeio_pio_bcopyin(vmeio_piomap_t piomap,
  37.                               iopaddr_t vmeaddr,
  38.                               caddr_t dest_sys_addr,
  39.                               int byte_count,
  40.                               int itmsz,
  41.                               int flags);
  42.  
  43.      int vmeio_pio_bcopyout(vmeio_piomap_t piomap,
  44.                             iopaddr_t vmeaddr,
  45.                             caddr_t src_sys_addr,
  46.                             size_t byte_count,
  47.                             int itmsz,
  48.                             int flags);
  49.  
  50.    AAAArrrrgggguuuummmmeeeennnnttttssss
  51.      _v_m_e__c_o_n_n     VMEbus connection point.
  52.  
  53.      _d_e_v__d_e_s_c     Device descriptor, usually 0.
  54.  
  55.      _s_p_a_c_e        Type of the VMEbus space.
  56.  
  57.      _v_m_e_a_d_d_r      The offset within the space.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. vvvvmmmmeeeeiiiioooo((((DDDD3333))))                                                            vvvvmmmmeeeeiiiioooo((((DDDD3333))))
  71.  
  72.  
  73.  
  74.      _b_y_t_e__c_o_u_n_t   Size of the mapping.
  75.  
  76.      _b_y_t_e__c_o_u_n_t__m_a_x  Maximum size of a single mapping.
  77.  
  78.      _f_l_a_g_s        User specifiable options.
  79.  
  80.      _p_i_o_m_a_p       The mapping acquired by the _v_m_e_i_o__p_i_o_m_a_p__a_l_l_o_c().
  81.  
  82.      _d_e_s_t__s_y_s__a_d_d_r   The system address which the data is copied to.
  83.  
  84.      _s_r_c__s_y_s__a_d_d_r    The system address which the data is copied from.
  85.  
  86.      _i_t_m_s_z        The unit of transfer.
  87.  
  88.    DDDDiiiirrrreeeecccctttt MMMMeeeemmmmoooorrrryyyy AAAAcccccccceeeessssssss
  89.      vmeio_dmamap_t vmeio_dmamap_alloc(vertex_hdl_t vme_conn,
  90.                                        device_desc_t dev_desc,
  91.                                        vmeio_space_t space,
  92.                                        size_t byte_count_max,
  93.                                        unsigned flags);
  94.  
  95.      iopaddr_t vmeio_dmamap_addr(vmeio_dmamap_t dmamap,
  96.                                  paddr_t paddr,
  97.                                  size_t byte_count);
  98.  
  99.      alenlist_t vmeio_dmamap_list(vmeio_dmamap_t dmamap,
  100.                                   alenlist_t phys_alenlist,
  101.                                   unsigned flags);
  102.  
  103.      void vmeio_dmamap_done(vmeio_dmamap_t dmamap);
  104.  
  105.      void vmeio_dmamap_free(vmeio_dmamap_t dmamap);
  106.  
  107.    AAAArrrrgggguuuummmmeeeennnnttttssss
  108.      _v_m_e__c_o_n_n     VMEbus connection point.
  109.  
  110.      _d_e_v__d_e_s_c     Device descriptor, usually zero.
  111.  
  112.      _s_p_a_c_e        Type of the VMEbus space.
  113.  
  114.      _b_y_t_e__c_o_u_n_t__m_a_x  Maximum size of a single mapping.
  115.  
  116.      _d_m_a_m_a_p       The mapping resources aquired through _v_m_e_i_o__d_m_a_m_a_p__a_l_l_o_c().
  117.  
  118.      _p_a_d_d_r        Physical address.
  119.  
  120.      _b_y_t_e__c_o_u_n_t   Size of the mapping.
  121.  
  122.      _p_h_y_s__a_l_e_n_l_i_s_t   The list of pairs of physical address and length.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. vvvvmmmmeeeeiiiioooo((((DDDD3333))))                                                            vvvvmmmmeeeeiiiioooo((((DDDD3333))))
  137.  
  138.  
  139.  
  140.      _f_l_a_g_s        Specifying attributes of the DMA mapping.
  141.  
  142.    IIIInnnntttteeeerrrrrrrruuuupppptttt HHHHaaaannnnddddlllliiiinnnngggg
  143.      vmeio_intr_t vmeio_intr_alloc(vertex_hdl_t vme_conn,
  144.                                    device_desc_t dev_desc,
  145.                                    vmeio_intr_vector_t vec,
  146.                                    vmeio_intr_level_t level,
  147.                                    vertex_hdl_t owner_dev,
  148.                                    unsigned flags);
  149.  
  150.      vmeio_intr_vector_t vmeio_intr_vector_get(vmeio_intr_t intr)
  151.  
  152.      int vmeio_intr_connect(vmeio_intr_t intr,
  153.                             intr_func_t intr_func,
  154.                             intr_arg_t intr_arg,
  155.                             void *thread);
  156.  
  157.      void vmeio_intr_disconnect(vmeio_intr_t intr);
  158.  
  159.      void vmeio_intr_free(vmeio_intr_t intr);
  160.  
  161.    AAAArrrrgggguuuummmmeeeennnnttttssss
  162.      _v_m_e__c_o_n_n     VMEbus connection point.
  163.  
  164.      _d_e_v__d_e_s_c     Device descriptor, usually zero.
  165.  
  166.      _v_e_c          Interrupt vector number.
  167.  
  168.      _l_e_v_e_l        VMEbus Interrupt level.
  169.  
  170.      _o_w_n_e_r__d_e_v    The vertex used to print messages about this particular
  171.                   interrupt, usually zero.
  172.  
  173.      _f_l_a_g_s        User specifiable options.
  174.  
  175.      _i_n_t_r         Interrupt handle acquired by _v_m_e_i_o__i_n_t_r__a_l_l_o_c().
  176.  
  177.      _i_n_t_r__f_u_n_c    The function used for interrupt service.
  178.  
  179.      _i_n_t_r__a_r_g     The argument passed to _i_n_t_r__f_u_n_c.
  180.  
  181. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  182.      On Origin and Onyx2 systems, _v_m_e_i_o provides a set of routines for VMEbus
  183.      kernel device drivers to set up services for their devices.  These
  184.      services include:
  185.  
  186.      +o   registering all instances of the device in the system.
  187.  
  188.      +o   constructing CPU addresses that the device can use to do PIO to the
  189.          device.
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. vvvvmmmmeeeeiiiioooo((((DDDD3333))))                                                            vvvvmmmmeeeeiiiioooo((((DDDD3333))))
  203.  
  204.  
  205.  
  206.      +o   constructing VMEbus addresses that the device can use to do DMA.
  207.  
  208.      +o   arranging for a function to be called when the device requests
  209.          interrupt service.
  210.  
  211.      +o   arranging for a function to be called when an error occurs during PIO
  212.          or DMA operations on the device.
  213.  
  214.    PPPPrrrrooooggggrrrraaaammmmmmmmeeeedddd IIIIOOOO
  215.      _v_m_e_i_o__p_i_o_m_a_p__a_l_l_o_c() allocates the PIO resources for the given
  216.      requirement. Return the handle of the PIO resources if success, 0
  217.      otherwise. The VMEbus specific flags include VME_PIOMAP_FIXED,
  218.      VME_PIOMAP_UNFIXED, and VME_DEBUG. VME_DEBUG is used to do more integrity
  219.      checking. Possibly, device driver writers can turn on this mode to sanity
  220.      check their drivers a bit, with some degree of performance degradation.
  221.  
  222.      _v_m_e_i_o__p_i_o_m_a_p__a_d_d_r() establishes a mapping from a VME bus address range to
  223.      a kernel virtual address range using the allocated PIO resources. Return
  224.      the kernel virtual address if success, 0 if otherwise.
  225.  
  226.      _v_m_e_i_o__p_i_o_m_a_p__d_o_n_e() notifies the system that a driver is done with using
  227.      the piomap resources obtained by the earlier _v_m_e_i_o__p_i_o_m_a_p__a_d_d_r() call.
  228.  
  229.      _v_m_e_i_o__p_i_o_m_a_p__f_r_e_e() frees the PIO mapping resources.
  230.  
  231.      _v_m_e_i_o__p_i_o__b_c_o_p_y_i_n() copies data from the device buffer to the system
  232.      memory efficiently. The unit of the transfer can be 1 byte, 2 bytes, 4
  233.      bytes, and 8 bytes. Return total bytes of successful transfer, -1 if
  234.      function fails.
  235.  
  236.      _v_m_e_i_o__p_i_o__b_c_o_p_y_o_u_t() copies data from the system memory to the device
  237.      buffer efficiently. The unit of the transfer can be 1 byte, 2 bytes, 4
  238.      bytes, and 8 bytes. Return total bytes of successful transfer, -1 if
  239.      function fails.
  240.  
  241.    DDDDiiiirrrreeeecccctttt MMMMeeeemmmmoooorrrryyyy AAAAcccccccceeeessssssss
  242.      _v_m_e_i_o__d_m_a_m_a_p__a_l_l_o_c() allocates mapping resources needed for DMA. Return
  243.      the handle of the new DMA map if success, 0 if failed. As described
  244.      before, VME_DEBUG can be used as a flag passed to have stronger integrity
  245.      checking over the life-span of the DMA map.  Flags available for this
  246.      call are:
  247.  
  248.      _VVVV_MMMM_EEEE_IIII_OOOO______DDDD_MMMM_AAAA______DDDD_AAAA_TTTT_AAAA
  249.              specifies that the DMA channel will be used for data streams.
  250.              Prefetch and postwrite are enabled on this mapping.
  251.  
  252.      _VVVV_MMMM_EEEE_IIII_OOOO______DDDD_MMMM_AAAA______CCCC_MMMM_DDDD
  253.              specifies that the DMA channel will be used for command
  254.              information. Prefetch and postwrite are disabled on this mapping.
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. vvvvmmmmeeeeiiiioooo((((DDDD3333))))                                                            vvvvmmmmeeeeiiiioooo((((DDDD3333))))
  269.  
  270.  
  271.  
  272.      _v_m_e_i_o__d_m_a_m_a_p__a_d_d_r() establishes a mapping from a physical address range
  273.      to a VMEbus address range by using the allocated DMA resources. Return
  274.      VMEbus address mapped to the physical addr range if success,
  275.      _VVVV_MMMM_EEEE_IIII_OOOO______DDDD_MMMM_AAAA______IIII_NNNN_VVVV_AAAA_LLLL_IIII_DDDD______AAAA_DDDD_DDDD_RRRR otherwise.
  276.  
  277.      _v_m_e_i_o__d_m_a_m_a_p__l_i_s_t() establishes the mapping from a list of (physical
  278.      address, length) to a list of (VMEbus address, length). Return the list
  279.      of (VMEbus address, length) if success, 0 if failed. The returned list
  280.      should be freed by the caller. Flags avalable for this call are:
  281.  
  282.      _VVVV_MMMM_EEEE_IIII_OOOO______IIII_NNNN_PPPP_LLLL_AAAA_CCCC_EEEE
  283.              requests that the list be modified in place when list operations
  284.              are performed.
  285.  
  286.      _VVVV_MMMM_EEEE_IIII_OOOO______NNNN_OOOO_SSSS_LLLL_EEEE_EEEE_PPPP
  287.              requests that the VMEbus provider not to sleep in resource
  288.              allocation and failure should be returned if sleep is necessary
  289.              for getting the resources.
  290.  
  291.      _v_m_e_i_o__d_m_a_m_a_p__d_o_n_e() notifies the system that a driver is done with using
  292.      the DMA mapping resource.
  293.  
  294.      _v_m_e_i_o__d_m_a_m_a_p__f_r_e_e() frees the DMA resources acquired by
  295.      _v_m_e_i_o__d_m_a_m_a_p__a_l_l_o_c() call.
  296.  
  297.    IIIInnnntttteeeerrrrrrrruuuupppptttt HHHHaaaannnnddddlllliiiinnnngggg
  298.      _v_m_e_i_o__i_n_t_r__a_l_l_o_c() allocates interrupt resources. This function is
  299.      usually called in <_d_r_v>__e_d_t_i_n_i_t().  In some cases, users have a VME
  300.      device which comes with a fixed interrupt vector number, or users like to
  301.      fix the interrupt vector for their devices. If so, they can specify the
  302.      vector number on the VECTOR line statement. And they can declare the
  303.      vector number here. In most of cases, users just need a vector, they can
  304.      pass VME_INTR_VECTOR_ANY in the vmeio_intr_vector_t field. Here,
  305.      VME_DEBUG can be specified as a flag to help debugging.
  306.  
  307.      _v_m_e_i_o__i_n_t_r__v_e_c_t_o_r__g_e_t() retrieves interrupt vector number from the
  308.      interrupt object. Usually, people will ask the system dynamically assign
  309.      an interrupt vector so that they can associate their interrupt handler.
  310.      They need this function to find out what interrupt vector number is
  311.      assigned to them so that they can program interrupt registers of their
  312.      devices. Sometimes, the driver already knows the vector number since they
  313.      have declared the fixed ones in the configuration file.
  314.  
  315.      _v_m_e_i_o__i_n_t_r__c_o_n_n_e_c_t() associates a software interrupt handler to the
  316.      hardware interrupt resources. Return 0 if success, -1 if failure.
  317.  
  318.      _v_m_e_i_o__i_n_t_r__d_i_s_c_o_n_n_e_c_t() disassociates the interrupt handler from the
  319.      specified interrupt.
  320.  
  321.      _v_m_e_i_o__i_n_t_r__f_r_e_e() frees the interrupt resources. Usually, the interrupt
  322.      vector allocated for the device is freed here.
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. vvvvmmmmeeeeiiiioooo((((DDDD3333))))                                                            vvvvmmmmeeeeiiiioooo((((DDDD3333))))
  335.  
  336.  
  337.  
  338. FFFFIIIILLLLEEEESSSS
  339.      /var/sysgen/system
  340.      /var/sysgen/master.d
  341.      /var/sysgen/boot
  342.  
  343. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  344.      "IRIX Device Driver Programmer's Guide"
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.                                                                         PPPPaaaaggggeeee 6666
  394.  
  395.  
  396.  
  397.